home *** CD-ROM | disk | FTP | other *** search
/ Mac Mania 2 / MacMania 2.toast / Demo's / Tools&Utilities / HyperCard / HyperWais 1.7 / README < prev    next >
Encoding:
Text File  |  1993-02-02  |  8.5 KB  |  244 lines  |  [TEXT/ttxt]
  1. HyperWais 1.7:
  2. --------------
  3.  
  4. Welcome to HyperWais, a Hypercard stack for searching Wide Area
  5. Information Servers.
  6.  
  7.  
  8.  
  9. What is HyperWais:
  10. ------------------
  11.  
  12. HyperWais is a hypercard stack which can be used to access Wide Area
  13. Information Servers (WAIS) on the internet, currently there about about
  14. 300 public access servers available.
  15.  
  16. HyperWais allows you to connect up to any number of servers, search
  17. them, download documents and view/save them either with built-in 
  18. handlers or using other applications to view them. Support is also 
  19. provided for doing relevance feedback. All this functionality is provided within hypercard in the form of a stack, in fact there are two stacks, 
  20. one built for Macs with small screens and one built for Macs with larger
  21. screens. Because the search interface is built using Hypercard, users
  22. can completely remodel it to their taste.
  23.  
  24. Two versions of the product are provided, one (HyperWais.sea.hqx) is
  25. aimed at users who just want to use the system, and the other
  26. (HyperWais.src.sea.hqx) includes all the C source code used to build
  27. HyperWais for those of you who want to see hows it's built.
  28.  
  29.  
  30.  
  31. Where can I get HyperWais:
  32. --------------------------
  33.  
  34. HyperWais can be obtained by anonymous FTP from:
  35.  
  36. mendel.welch.jhu.edu:/pub/fs/HyperWais.sea.hqx,
  37. mendel.welch.jhu.edu:/pub/fs/HyperWais.src.sea.hqx,
  38.  
  39. the internet address for mendel is [128.220.59.42],
  40.  
  41.  
  42. or from:
  43.  
  44. sunsite.oit.unc.edu:/pub/wais/Mac/HyperWais.sea.hqx,
  45. sunsite.oit.unc.edu:/pub/wais/Mac/HyperWais.src.sea.hqx,
  46.  
  47. the internet address for sunsite is [152.2.22.81].
  48.  
  49. HyperWais.sea.hqx contains the User Distribution and
  50. HyperWais.src.sea.hqx contains the Source Code Distribution.
  51.  
  52.  
  53.  
  54. What does HyperWais cost:
  55. -------------------------
  56.  
  57. Nothing, but be sure to read the COPYRIGHT file to see what the 
  58. restrictions are.
  59.  
  60.  
  61.  
  62. What is included in the User distribution:
  63. ------------------------------------------
  64.  
  65. After you have uncompressed the archive, you should find:  
  66.  
  67. - This file (named README).
  68.  
  69. - The copyright file (named COPYRIGHT).
  70.  
  71. - A Hypercard stack called HyperWais, which is a sample stack for
  72. searching WAIS databases. This stack contains a set of XCMDs which
  73. allow the stack to communicate (via Apple Events) with the "Wais
  74. Listener". There is also another stacks called HyperWais 12 for 12"
  75. monitors.
  76.  
  77. - A application called "Wais Listener", this is the Faceless Background
  78. Application (FBA) which allows the Hypercard stack to communicate with
  79. WAIS servers. This application just sits in the background and listens
  80. out to Apple Events. All you need to do is start it up. Note that the
  81. "Wais Listener" will grab a chunk of memory (about 450K) which will be
  82. added to the system software in the "About this mac" box.
  83.  
  84. - Another application called "Wais Listener.debug", this is the same
  85. application as the "Wais Listener" but will have a visible debug window
  86. which will list out all the events/data received and events/data
  87. returned. You may want to use this application to see what is going
  88. on.  Both "Wais Listener" and "Wais Listener.debug" create log files
  89. which can be looked at with any text editor.
  90.  
  91. - A folder called wais-sources where HyperWais stores the WAIS source
  92. description files.
  93.  
  94. - A folder called wais-documents where HyperWais stores some WAIS
  95. document files.
  96.  
  97. - A folder called wais-questions which does nothing at this time.
  98.  
  99. - Dont forget to read the release notes located in the Release Notes
  100. folder, these list out all the changes that were made with each
  101. version of HyperWais.
  102.  
  103.  
  104.  
  105. What is included in the Source distribution:
  106. --------------------------------------------
  107.  
  108. - All that is included in the User Distribution.
  109.  
  110. - All the source code (there is a lot and I have yet to list it).
  111.  
  112.  
  113.  
  114. Other software you need to run HyperWais:
  115. -----------------------------------------
  116.  
  117. To run HyperWais you will need to run system 7.0, Hypercard 2.1 and
  118. MacTCP 1.1. Hypercard will have to be allocated 1500K of memory, this
  119. is done using the "Get Info" menu in the Finder.
  120.  
  121. The Wais Listener should have about 450K of allocated to it.
  122.  
  123. If you want to compile the source code, you will need Think C 5.0.X ( There
  124. is a bug in 5.0.3 and I would not recomend using it ), and the MacTCP
  125. toolkit from APDA.  The software was built with the standard library
  126. distribution from Symantec, but you will have to recompile them with the 
  127. 4 byte integers option set, ( you may well be able to compile the application
  128. with 2 byte integers set, but you will need to recompile *all* the code in the
  129. distribution software).
  130. Note that I have been very specific about my integers, so compiling
  131. with either 2 byte integers or 4 bytes integers should make no difference.
  132.  
  133.  
  134.  
  135. Starting up:
  136. ------------
  137.  
  138. To start up you need to launch the "Wais Listener" application, then
  139. start HyperWais. HyperWais will need the wais-sources folder and the
  140. wais-documents folder in the folder it is located in (these are in the
  141. archive and should be created automatically). Note that the "Wais Listener"
  142. needs MacTCP to communicate with wais sources.  You may want to place the 
  143. "Wais Listener" in the startup folder located in the system folder. 
  144. This will ensure that the "Wais Listener" is started up everytime you 
  145. start up your mac.
  146.  
  147.  
  148.  
  149. Some limitations:
  150. -----------------
  151.  
  152. The "Wais Listener" will support any number of connections, any number
  153. of open sources per connection, number of document headlines per
  154. connection and any number of relevance feedback entries per
  155. connection.  The main limitation imposed is the amount of memory
  156. available to the "Wais Listener'. The connections can be opened by
  157. clients located either on the same macintosh as the "Wais Listener" or on 
  158. a different macintosh. This feature would enable you to set up a 
  159. "Wais Listener" gateway on one macintosh with a connection to
  160. the Internet and have a number of other macintoshs using appletalk to
  161. connect up to that Wais Listener.
  162.  
  163.  
  164.  
  165. Technical Overview:
  166. -------------------
  167.  
  168. The are three components to the HyperWais software:
  169.  
  170. - There are a set of C routines which handle the MacTCP communications
  171. and the WAIS protocols. These can be linked in with any other
  172. applications which want to use WAIS.
  173.  
  174. - On top of the C routines, there is the module that handle the Apple
  175. Events and maps them to the C routines.
  176.  
  177. - There is also another Apple Event module which deals with the
  178. communication between the client program and the "Wais Listener".
  179.  
  180.  
  181.  
  182. Below is a diagram of how the software is layered. There are a set of
  183. basic routines which support basic services to wais servers via
  184. MacTCP. These routines provide very basic services such as connection,
  185. disconnection, init, query and downloading data. The glue routines
  186. provide an abstracted view of the basic routines and allow a user to
  187. access wais services without having to worry about the protocol and
  188. MacTCP. These are the routines that someone would use to integrate wais
  189. in their products.
  190.  
  191. There is an FBA (called the "Wais Listener") which will listen out to
  192. apple events and call the appropriate glue routines. This FBA can
  193. either run on the same mac as the wais client (using the FBA that is)
  194. or on another mac. The FBA will support any number of sessions either
  195. from the same client or different client, and either from the same user
  196. or different users on different mac.
  197.  
  198. At the other end, there are a set of stubs which implement the Apple
  199. Events calling functions making it easier for people to integrate them
  200. into their applications. And on top of that a set of XFCN for Hypercard
  201. or others.
  202.  
  203. All this is written in a layered manner so that people who want to
  204. integrate wais services into their applications can do so at various
  205. levels. Either one could use Apple Events, or call the glue routines
  206. directly and just link in the C library into their application, or if
  207. you want to program on the 'bare metal', you could go directly against
  208. the basic routines.
  209.  
  210.  
  211.       -----------------------
  212.       |      XFCN           |
  213.       ----------------------- 
  214.       |   Apple Events      |
  215.       ----------------------- 
  216.               |
  217.               |
  218.               |
  219.       -----------------------         This whole block
  220.       |   Apple Events      |         is the wais listener
  221.       ----------------------- 
  222.       |    Glue Routines    |
  223.       ----------------------- 
  224.       |    Basic Routines   |
  225.       ----------------------- 
  226.       |    WAIS protocol    |
  227.       ----------------------- 
  228.       |    MacTCP           |
  229.       ----------------------- 
  230.  
  231.  
  232.  
  233. francois 
  234.  
  235. Francois Schiettecatte
  236. Software Engineer
  237. Advanced Technology Group
  238. Welch Medical Library
  239. Johns Hopkins University
  240. Internet: francois@library.welch.jhu.edu
  241. Phone    : (410) 955-7581
  242.  
  243.  
  244.